extends layout

append style
  link(rel="stylesheet", href="/docs/css/inlinecpc.css")
  script(type="text/javascript" src="/docs/js/native.js")

block content
  :markdown
    ## Deprecation Warnings

    <script>
      _native.init("CK7DT53U",{
        targetClass: 'native-inline'
      });
    </script>

    <div class="native-inline">
      <a href="#native_link#"><span class="sponsor">Sponsor</span> #native_company# — #native_desc#</a>
    </div>

    There are several deprecations in the [MongoDB Node.js driver](http://npmjs.com/package/mongodb)
    that Mongoose users should be aware of. Mongoose provides options to work
    around these deprecation warnings, but you need to test whether these options
    cause any problems for your application. Please [report any issues on GitHub](https://github.com/Automattic/mongoose/issues/new).

    ## Summary

    To fix all deprecation warnings, follow the below steps:

    * `mongoose.set('useNewUrlParser', true);`
    * `mongoose.set('useFindAndModify', false);`
    * `mongoose.set('useCreateIndex', true);`
    * Replace `update()` with `updateOne()`, `updateMany()`, or `replaceOne()`
    * Replace `remove()` with `deleteOne()` or `deleteMany()`.
    * Replace `count()` with `countDocuments()`, unless you want to count how many documents are in the whole collection (no filter). In the latter case, use `estimatedDocumentCount()`.

    Read below for more a more detailed description of each deprecation warning.

    ## The `useNewUrlParser` Option

    By default, `mongoose.connect()` will print out the below warning:

    ```
    DeprecationWarning: current URL string parser is deprecated, and will be
    removed in a future version. To use the new parser, pass option
    { useNewUrlParser: true } to MongoClient.connect.
    ```

    The MongoDB Node.js driver rewrote the tool it uses to parse [MongoDB connection strings](https://docs.mongodb.com/manual/reference/connection-string/).
    Because this is such a big change, they put the new connection string parser
    behind a flag. To turn on this option, pass the `useNewUrlParser` option to
    [`mongoose.connect()`](/docs/api.html#mongoose_Mongoose-connect)
    or [`mongoose.createConnection()`](/docs/api.html#mongoose_Mongoose-createConnection).

    ```javascript
    mongoose.connect(uri, { useNewUrlParser: true });
    mongoose.createConnection(uri, { useNewUrlParser: true });
    ```

    You can also [set the global `useNewUrlParser` option](/docs/api.html#mongoose_Mongoose-set)
    to turn on `useNewUrlParser` for every connection by default.

    ```javascript
    // Optional. Use this if you create a lot of connections and don't want
    // to copy/paste `{ useNewUrlParser: true }`.
    mongoose.set('useNewUrlParser', true);
    ```

    To test your app with `{ useNewUrlParser: true }`, you only need to check
    whether your app successfully connects. Once Mongoose has successfully
    connected, the URL parser is no longer important. If you can't connect
    with `{ useNewUrlParser: true }`, please [open an issue on GitHub](https://github.com/Automattic/mongoose/issues/new).

    ## `findAndModify()`

    If you use [`Model.findOneAndUpdate()`](/docs/api.html#model_Model.findOneAndUpdate),
    by default you'll see the below deprecation warning.

    ```
    DeprecationWarning: collection.findAndModify is deprecated. Use findOneAndUpdate, findOneAndReplace or findOneAndDelete instead.
    ```

    Mongoose's `findOneAndUpdate()` long pre-dates the MongoDB driver's `findOneAndUpdate()`
    function, so it uses the MongoDB driver's [`findAndModify()` function](http://mongodb.github.io/node-mongodb-native/3.1/api/Collection.html#findAndModify)
    instead. You can opt in to using using the MongoDB driver's `findOneAndUpdate()`
    function using the [`useFindAndModify` global option](/docs/api.html#mongoose_Mongoose-set).

    ```javascript
    // Make Mongoose use `findOneAndUpdate()`. Note that this option is `true`
    // by default, you need to set it to false.
    mongoose.set('useFindAndModify', false);
    ```

    You can also configure `useFindAndModify` by passing it through the connection options.
    ```javascript
    mongoose.connect(uri, { useFindAndModify: false });
    ```

    This option affects the following model and query functions. There are
    no intentional backwards breaking changes, so you should be able to turn
    this option on without any code changes. If you discover any issues,
    please [open an issue on GitHub](https://github.com/Automattic/mongoose/issues/new).

    * [`Model.findByIdAndDelete()`](/docs/api.html#model_Model.findByIdAndDelete)
    * [`Model.findByIdAndRemove()`](/docs/api.html#model_Model.findByIdAndRemove)
    * [`Model.findByIdAndUpdate()`](/docs/api.html#model_Model.findByIdAndUpdate)
    * [`Model.findOneAndDelete()`](/docs/api.html#model_Model.findOneAndDelete)
    * [`Model.findOneAndRemove()`](/docs/api.html#model_Model.findOneAndRemove)
    * [`Model.findOneAndUpdate()`](/docs/api.html#model_Model.findOneAndUpdate)
    * [`Query.findOneAndDelete()`](/docs/api.html#query_Query-findOneAndDelete)
    * [`Query.findOneAndRemove()`](/docs/api.html#query_Query-findOneAndRemove)
    * [`Query.findOneAndUpdate()`](/docs/api.html#query_Query-findOneAndUpdate)

    ## `ensureIndex()`

    If you define [indexes in your Mongoose schemas](https://mongoosejs.com/docs/guide.html#indexes), you'll see the below
    deprecation warning.

    ```
    DeprecationWarning: collection.ensureIndex is deprecated. Use createIndexes
    instead.
    ```

    By default, Mongoose 5.x calls the [MongoDB driver's `ensureIndex()` function](http://mongodb.github.io/node-mongodb-native/3.1/api/Collection.html#ensureIndex).
    The MongoDB driver deprecated this function in favor of [`createIndex()`](http://mongodb.github.io/node-mongodb-native/3.1/api/Collection.html#createIndex).
    Set the [`useCreateIndex` global option](/docs/api.html#mongoose_Mongoose-set) to opt in to making Mongoose use `createIndex()` instead.

    ```javascript
    mongoose.set('useCreateIndex', true);
    ```

    You can also configure `useCreateIndex` by passing it through the connection options.
    ```javascript
    mongoose.connect(uri, { useCreateIndex: true });
    ```

    There are no intentional backwards breaking changes with the `useCreateIndex`
    option, so you should be able to turn
    this option on without any code changes. If you discover any issues,
    please [open an issue on GitHub](https://github.com/Automattic/mongoose/issues/new).

    ## `remove()`

    The MongoDB driver's [`remove()` function](http://mongodb.github.io/node-mongodb-native/3.1/api/Collection.html#remove) is deprecated in favor of `deleteOne()` and `deleteMany()`. This is to comply with
    the [MongoDB CRUD specification](https://github.com/mongodb/specifications/blob/master/source/crud/crud.rst),
    which aims to provide a consistent API for CRUD operations across all MongoDB
    drivers.

    ```
    DeprecationWarning: collection.remove is deprecated. Use deleteOne,
    deleteMany, or bulkWrite instead.
    ```

    To remove this deprecation warning, replace any usage of `remove()` with
    `deleteMany()`, _unless_ you specify the [`single` option to `remove()`](/docs/api.html#model_Model.remove). The `single`
    option limited `remove()` to deleting at most one document, so you should
    replace `remove(filter, { single: true })` with `deleteOne(filter)`.

    ```javascript
    // Replace this:
    MyModel.remove({ foo: 'bar' });
    // With this:
    MyModel.deleteMany({ foo: 'bar' });

    // Replace this:
    MyModel.remove({ answer: 42 }, { single: true });
    // With this:
    MyModel.deleteOne({ answer: 42 });
    ```

    ## `update()`

    Like `remove()`, the [`update()` function](/docs/api.html#model_Model.update) is deprecated in favor
    of the more explicit [`updateOne()`](/docs/api.html#model_Model.updateOne), [`updateMany()`](/docs/api.html#model_Model.updateMany), and [`replaceOne()`](/docs/api.html#model_Model.replaceOne) functions. You should replace
    `update()` with `updateOne()`, unless you use the [`multi` or `overwrite` options](/docs/api.html#model_Model.update).

    ```
    collection.update is deprecated. Use updateOne, updateMany, or bulkWrite
    instead.
    ```

    ```javascript
    // Replace this:
    MyModel.update({ foo: 'bar' }, { answer: 42 });
    // With this:
    MyModel.updateOne({ foo: 'bar' }, { answer: 42 });

    // If you use `overwrite: true`, you should use `replaceOne()` instead:
    MyModel.update(filter, update, { overwrite: true });
    // Replace with this:
    MyModel.replaceOne(filter, update);

    // If you use `multi: true`, you should use `updateMany()` instead:
    MyModel.update(filter, update, { multi: true });
    // Replace with this:
    MyModel.updateMany(filter, update);
    ```

    ## `count()`

    The MongoDB server has deprecated the `count()` function in favor of two
    separate functions, [`countDocuments()`](#query_Query-countDocuments) and
    [`estimatedDocumentCount()`](#query_Query-estimatedDocumentCount).

    ```
    DeprecationWarning: collection.count is deprecated, and will be removed in a future version. Use collection.countDocuments or collection.estimatedDocumentCount instead
    ```

    The difference between the two is `countDocuments()` can accept a filter
    parameter like [`find()`](#query_Query-find). The `estimatedDocumentCount()`
    function is faster, but can only tell you the total number of documents in
    a collection. You cannot pass a `filter` to `estimatedDocumentCount()`.

    To migrate, replace `count()` with `countDocuments()` _unless_ you do not
    pass any arguments to `count()`. If you use `count()` to count all documents
    in a collection as opposed to counting documents that match a query, use
    `estimatedDocumentCount()` instead of `countDocuments()`.

    ```javascript
    // Replace this:
    MyModel.count({ answer: 42 });
    // With this:
    MyModel.countDocuments({ answer: 42 });

    // If you're counting all documents in the collection, use
    // `estimatedDocumentCount()` instead.
    MyModel.count();
    // Replace with:
    MyModel.estimatedDocumentCount();

    // Replace this:
    MyModel.find({ answer: 42 }).count().exec();
    // With this:
    MyModel.find({ answer: 42 }).countDocuments().exec();

    // Replace this:
    MyModel.find().count().exec();
    // With this, since there's no filter
    MyModel.find().estimatedDocumentCount().exec();
    ```

    ## `GridStore`

    If you're using [gridfs-stream](https://www.npmjs.com/package/gridfs-stream),
    you'll see the below deprecation warning:

    ```
    DeprecationWarning: GridStore is deprecated, and will be removed in a
    future version. Please use GridFSBucket instead.
    ```

    That is because gridfs-stream relies on a [deprecated MongoDB driver class](http://mongodb.github.io/node-mongodb-native/3.1/api/GridStore.html).
    You should instead use the [MongoDB driver's own streaming API](https://thecodebarbarian.com/mongodb-gridfs-stream).

    ```javascript
    // Replace this:
    const conn = mongoose.createConnection('mongodb://localhost:27017/gfstest');
    const gfs = require('gridfs-store')(conn.db);
    const writeStream = gfs.createWriteStream({ filename: 'test.dat' });

    // With this:
    const conn = mongoose.createConnection('mongodb://localhost:27017/gfstest');
    const gridFSBucket = new mongoose.mongo.GridFSBucket(conn.db);
    const writeStream = gridFSBucket.openUploadStream('test.dat');
    ```